pymongo.MongoClient

Overview

  • 產生一個client物件,用來連接MongoDB、replica set、或set of mongoses。
  • client物件設計為thread-safe並支援connection-pooling。
  • 如果網路連線中斷導致操作失敗,會產生ConnectionFailure並在背景重新連線,應用程式要用try...except處理此例外情況,然後繼續執行。
  • 舊版的alive()拿掉了,因為無論是否已連線,當操作時都會在背景自動連線。
  • 連線到mongoses時,會在背景監控每台mongoses的網路延遲,並自動將操作分散到延遲較低的機器上。

Init Parameters

  1. host: 可以是單純的ip address,也可以是完整的mongodb URI,例如'mongodb://user:pass@10.0.0.1:27017'。在URI中設定的port會覆蓋port參數的設定。ip address可以是ipv6,例如'[::1]'等同於'localhost'。如果要連線到replica set或mongoses,host參數可以是list of strings,連線時會一個一個嘗試,並使用最後一個連線正確的host。預設值為'localhost'
  2. port: 連線的port number,預設為27017
  3. document_class: 執行query時,傳回文件的資料型態,預設為dict
  4. tz_aware: 設為True,文件中的時間會作時區調整,預設為False
  5. connect: 設為True,會馬上在背景連線到MongoDB;預設為`False,會在第一次操作時才連線。
  6. 連線參數
    • maxPoolSize: 這個client的connection pool大小,代表同時連線的數量,預設為100,不可以設為0
    • socketTimeoutMS: 送出操作後等多少milliseconds算是timeout,預設為None代表沒有timeout。
    • connectTimeoutMS: 第一次連線等多少milliseconds會判定為server離線,預設為20000代表20秒,設為None代表沒有timeout。
    • serverSelectionTimeoutMS: 當host是list時,總共可以花多少milliseconds來找正確的server。對應每個server會產生一個連線,每個連線的時間受限於connectTimeoutMS。預設值為30000代表30秒。
    • waitQueueTimeoutMS: 當connection pool已滿時,新的連線等多少milliseconds算是timeout,預設為None代表沒有timeout。
    • waitQueueMultiple: 當connection pool已滿時,可以有多少個等待連線。waitQueueMultiple乘上maxPoolSize就是最大等待數量。預設值為None代表沒有限制。
    • socketKeepAlive: 已連線的socket是否要定期送keep-alive來保持連線。預設為False
    • event_listeners: 包含event listener的list或tuple。
  7. 寫入保險參數
    • w: 當連線到replica set時,寫入操作應該要複製幾次。例如w=3代表寫入primary後,會被block直到文件複製兩次。設w=0表示不考慮。
    • wtimeout: 必須和w一起使用,表示write propagation要等多少milliseconds算是timeout。
    • j: 設為True,寫入時要等真的寫入journal才會返回。在MongoDB 2.6之前的版本此參數無效果。在MongoDB 2.6之後,如果MongoDB沒有開journaling功能,則每次寫入都會產生exception。此參數不能與fsync同時使用。
    • fsync: 設為True,如果MongoDB沒有journaling,會等資料真的寫入硬碟才會返回。如果MongoDB有journaling,則效果與j相同,會等寫入journal才返回。此參數不能與j同時使用。
  8. Replica Set參數
    • replicaSet: 設定要連線的replica set的名稱,連線時會從host list中找所有符合此名稱的member,預設為None
    • read_preference: 所有可用的read preference參數請參考ReadPreference。預設值為PRIMARY
  9. SSL參數
    • ssl: 設為True代表使用SSL連線,預設為False
    • ssl_keyfile: 代表private key的檔案位置,設定此值會使ssl=True。預設值為None
    • ssl_certfile: 代表certificate的檔案位置,設定此值會使ssl=True。預設值為None
    • ssl_cert_reqs: 反向連線時是否需要驗證,此參數可用的值為ssl.CERT_NONE(不需驗證)、ssl.CERT_OPTIONAL(不需驗證,但有提供驗證機制)、ssl.CERT_REQUIRED(強制驗證)。如果設為ssl.CERT_OPTIONALssl.CERT_REQUIRED,則CA certificate會優先從ssl_ca_certs參數取得,如果沒有則向作業系統索取。設定此值會使ssl=True。當ssl=True時,預設值為ssl.CERT_REQUIRED
    • ssl_ca_certs: 代表CA cerficicate的檔案位置,用來驗證反向連線,設定此值會使ssl=True。預設值為None
    • ssl_match_hostname: 預設值為True,表示用Python的ssl.match_hostname()驗證hostname。要設為False前要小心,可能會讓你的應用程式受到man-in-the-middle攻擊。
  10. 讀取保險參數
    • readConcernLevel: 設定讀取操作的isolation level。例如設為majority只會傳回寫入超過半數node的資料,一般都不設定使用server預設值。

Methods and Members

  1. close(): 結束所有connection pool的連線,並停止monitor thread。但如果對closed client作操作,又會在背景自動連線並啟動monitor thread。
  2. client[db_name]client.db_name: 傳回db_name對應的Database物件。如果該名稱不存在,會傳回InvalidName
  3. address: 一個tuple (host, port)代表目前的連線。如果這個client是連線到mongoses,讀取此值會產生InvalidOperation,應該用nodes取代。如果client未連線,則讀取此值會自動連線,過程中可能產生ServerSelectionTimeoutError
  4. is_primary: True表示已經連線而且可以寫入。如果client未連線,則讀取此值會自動連線,過程中可能產生ServerSelectionTimeoutError
  5. is_mongos: True表示連線到mongos。如果client未連線,則讀取此值會自動連線,過程中可能產生ServerSelectionTimeoutError
  6. max_pool_size: 同時連線的socket的最大數量。如果pool達到此數量,所有操作都會block,直到其他socket釋放出空位為止。如果有設waitQueueTimeoutMS,則block的時間有上限。
  7. nodes: 目前連線的server清單,資料型態是frozenset。當連線到replica set時,這個清單會隨時改變,在剛開始還沒連線時也可能為空。
  8. max_bson_size: server最大的BSON物件是多少bytes。如果client未連線,則讀取此值會自動連線,過程中可能產生ServerSelectionTimeoutError
  9. max_message_size: server最長的message是多少bytes。如果client未連線,則讀取此值會自動連線,過程中可能產生ServerSelectionTimeoutError
  10. read_preference: 唯讀的read preference。
  11. write_concern: 唯讀的write concern。
  12. is_locked: server是否為鎖定狀態。鎖定時所有write都會被block,但read仍然可以用。要透過unlock()來解鎖。
  13. database_names(): 傳回所有database的名稱。
  14. drop_database(name_or_database): 刪除一個database,參數是database的名稱或是Database物件,資料型態錯誤會產生TypeError
  15. get_default_database(): 如果URI中有設定default database,可透過此方法讀取,否則會產生ConfigurationError
  16. get_database(name, codec_options=None, read_preference=None, write_concern=None, read_concern=None): 根據給定的名稱和選項取得Database物件。通常用在你希望的選擇與client預設值不同時。
    • codec_options: None或是CodecOptions物件
    • read_preference: None或是pymongo.read_preferences所屬的物件
    • write_concern: None或是WriteConcern物件
    • read_concern: None或是ReadConcern物件
  17. server_info(): 傳回server資訊。
  18. close_cursor(cursor_id, address=None): 關閉指定cursor的連線,如果cursor_id不是intlong會產生TypeErroraddress可設為(host, port)
  19. kill_cursors(cursor_id, address=None): 送出kill message給指定的cursor,如果cursor_id不是intlong會產生TypeErroraddress可設為(host, port)
  20. set_cursor_manager(manager_class): 設定client cursor manager,manager_class必須是CursorManager的subclass。cursor manager用來決定什麼時候要真正殺掉一個closed cursor。
  21. fsync(**kwargs): 送出所有延遲的寫入,參數設lock=True會在送出後鎖定server來禁止寫入,參數設async=True則會馬上返回。lockasync不可以同時使用。在Windows,MongoDB不支援async模式。
  22. unlock(): 解除server的鎖定。

pymongo.database.Database

Overview

  • Database level的工具

Init Parameters

  1. client: 一個MongoClient物件。
  2. name: database的名稱,如果不是字串會產生TypeError,如果不存在會產生InvalidName
  3. codec_options: CodecOptions物件或是None使用client的設定。
  4. read_preference: 設定read preference或是None使用client.read_preference的設定。
  5. write_concern: WriteConcern物件或是None使用client的設定。
  6. read_concern: ReadConcern物件或是None使用client的設定。

Methods and Members

  1. db[collection_name]db.collection_name: 取得名稱為collection_nameCollection物件,如果名稱不存在會產生InvalidName
  2. codec_options: 唯讀的CodecOptions物件
  3. read_preference: 唯讀的read preference
  4. write_concern: 唯讀的WriteConcern物件
  5. add_user(name, password=None, read_only=None, **kwargs)
    • 為這個database新增使者
    • name: 使用者名稱。
    • password: 使用者密碼,如果使用者已存在,則會修改密碼。
    • read_only: 設為True表示使用者只有讀的權限。
  6. authenticate(name, password, source, mechanism, **kwargs)
    • 登入使用者以取得database使用權限,權限會持續到client物件消失或是呼叫logout()
    • 多次登入但用不同的credential是不合法的,應該先logout()登出再重新登入。
    • 多個thread共用一個client時,只需登入一次。如果希望多個thread用不同的帳號密碼,應該獨立client。
    • 驗證失敗會產生PyMongoError的subclass。
    • name: 使用者名稱。如果不是字串會產生TypeError
    • password: 使用者密碼。如果不是字串會產生TypeError
    • source: 要登入的database名稱,不指定代表目前的database。如果不是字串會產生TypeError
    • mechanism: 驗證機制,預設為'DEFAULT',代表SCRAM-SHA-1
  7. client: 這個Database對應的MongoClient物件。
  8. collection_names(include_system_collections)
    • 取得collection名稱列表。
    • include_system_collections: 預設True會包含系統的collection,例如system.indexes
  9. command(command, value, check, allowable_errors, read_preference, codec_option, **kwargs)
    • command: 如果command是字串,會送出{command: value}到server上。如果commanddict,就直接送出。如果command是字串,也可以用kwargs補充,例如command('aaa','bbb',cc='dd')會送出{aaa:'bbb', cc:'dd'}
    • value: 作為第一個command的參數。
    • check: 是否檢查回應,預設為True,當回應有錯誤時,會產生OperationFailure
    • allowable_errors: 如果check=True,則忽略這些錯誤。預設為None
    • read_preference: 這個操作的read preference,預設為Primary()
    • codec_options: 一個CodecOptions物件,預設為CodecOptions(document_class=dict, tz_aware=False, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=None)
  10. create_collection(name, codec_options, read_preference, write_concern, read_concern, **kwargs)
    • 在此database建立一個新的collection。一般情況下,建立collection是自動的,但如果你希望建立時有其他參數,就可以用此方法。如果collection已經存在,會產生CollectionInvalid
    • name: 新建的collection名稱。
    • codec_options: 指定CodecOptions物件,預設為None
    • read_preference: 指定read preference,預設為None
    • write_concern: 指定WriteConcern物件,預設為None
    • read_concern: 指定ReadConcern物件,預設為None
    • size: 初始化時的容量(bytes)。如果capped=True,則這個值代表collection的最大容量。
    • capped: 設為True會變成capped collection。
    • max: 如果capped=True,這個值代表最大的物件數量。
  11. current_op(include_all=False): 傳回目前正執行中的operation,如果include_all=True則會包含idle中的operation。
  12. dereference(dbref, **kwargs): 根據DBRef找到對應的文件。如果dbref不是一個DBRef物件會產生TypeError。如果找不到文件,會傳回None。如果文件所在的database與目前的不同,會產生ValueErrorkwargs可以給如同find()在用的參數。
  13. drop_collection(name_or_collection): 刪除一個collection,name_or_collection是collection名稱或是Collection物件。
  14. get_collection(name, codec_options=None, read_preference=None, write_concern=None, read_concern=None)
    • 通常在你要取得的collection的codec與database預設值不同時,才需要用到此方法。
    • name: 要取得的collection名稱。
    • codec_options: 指定CodecOptions物件,預設為None
    • read_preference: 指定read preference,預設為None
    • write_concern: 指定WriteConcern物件,預設為None
    • read_concern: 指定ReadConcern物件,預設為None
  15. incoming_copying_manipulators: 一群copying manipulator,用來處理輸入的SON。
  16. incoming_manipulators: 一群manipulator,用來處理輸入的SON。
  17. logout(): 登出目前的帳號。
  18. name: Database的名稱。
  19. outgoing_copying_manipulators: 一群copying manipulator,用來處理輸出的SON。
  20. outgoing_manipulators: 一群manipulator,用來處理輸出的SON。
  21. profiling_info(): 傳回profiling資訊。
  22. profiling_level(): 傳回profiling level,值為{OFF, SLOW_ONLY, ALL}
  23. set_profiling_level(level, slow_ms=None): 設定profiling level,level可以設為{OFF, SLOW_ONLY, ALL}。OFF代表不作profiling,SLOW_ONLY代表只看slow operations,ALL代表對所有operations作profiling。執行時間超過slow_ms的operation會視為slow operation。
  24. remove_user(name): 移除使用者帳號name
  25. system_js: 傳回database的SystemJS helper物件。
  26. validate_collection(name_or_collection, scandata=False, full=False)
    • 傳回正確性資訊,如果有結構不正確的地方會產生CollectionInvalid
    • name_or_collection: collection名稱或是Collection物件。
    • scandata: 設為True,則除了結構,會作額外的檢查。預設為False
    • full: 設為True,在scandata=True時,會詳細檢查document的正確性。預設為False

pymongo.database.SystemJS(database)

用途

產生javascript的函式或物件,以協助database操作。SystemJS不需要自己產生,一律透過db.system_js來取得。

pymongo.collection.Collection

Overview

  • Collection level的工具

Init Parameters

  1. database: database的名稱。
  2. name: collection的名稱,如果不是字串會產生TypeError,如果不存在會產生InvalidName
  3. create: 設為True會馬上建立collection,預設為False表示第一次操作時才會建立。
  4. 其他參數
    • codec_options: 預設為None會延用database的設定,或是設為CodecOptions物件
    • read_preference: 預設為None會延用database的設定,或是設為read preference物件
    • write_concern: 預設為None會延用database的設定,或是設為WriteConcern物件
    • read_concern: 預設為None會延用database的設定,或是設為ReadConcern物件

Methods and Members

  1. collection[name]collection.name: 取得名稱為name的sub-collection,名稱不正確會產生InvalidName
  2. fullname: 這個collection的完整名稱,通常是db_name.collection_name
  3. database: 指向所在的database的Database物件。
  4. codec_options: 唯讀的CodecOptions物件。
  5. read_preference: 唯讀的read preference。
  6. write_concern: 唯讀的WriteConcern物件。
  7. with_options(codec_options=None, read_preference=None, write_concern=None, read_concern=None): 以新的參數產生一個複製的Collection物件。
  8. bulk_write(requests, ordered=True, bypass_document_validation=False)
    • 送出一連串的寫入操作,傳回值是BulkWriteResult物件。
      • acknowledged: 當WriteConcern(w=0)時,acknowledged會傳回False,其他情況會傳回True
      • bulk_api_result: 傳回值的原始資訊。
      • deleted_count: 刪除documents的數量。
      • inserted_count: 插入documents的數量。
      • matched_count: 符合update條件的documents的數量。
      • modified_count: 修改documents的數量。
      • upserted_count: ReplaceOne插入的documents的數量。
      • upserted_ids: ReplaceOne插入的documents的id。
    • requests是list of write operations (InsertOne, UpdateOne, UpdateMany, ReplaceOne, DeleteOne, DeleteMany)
    • ordered: 預設值True代表這些操作會依序執行。如果執行中發生錯誤,後面的操作都會放棄。設為False表示可能平行處理,順序是隨機的,所有的操作都會嘗試一次。
    • bypass_document_validation: 預設值False,設為True代表允許不合法的document被寫入。
  9. insert_one(document, bypass_document_validation=False)
    • 插入一份文件,傳回值為InsertOneResult物件。
      • acknowledged: 當WriteConcern(w=0)時,acknowledged會傳回False,其他情況會傳回True
      • inserted_id: 插入文件的id。
    • document: 要插入的文件,必須是mutable mapping,如果沒有_id欄位,會自動產生_id
    • bypass_document_validation: 預設值False,設為True代表允許不合法的document被寫入。
  10. insert_many(documents, ordered=True, bypass_document_validation=False)
    • 插入多份文件,傳回值為InsertManyResult物件。
      • acknowledged: 當WriteConcern(w=0)時,acknowledged會傳回False,其他情況會傳回True
      • inserted_ids: 插入文件的id。
    • ordered: 預設值True代表這些操作會依序執行。如果執行中發生錯誤,後面的操作都會放棄。設為False表示可能平行處理,順序是隨機的,所有的操作都會嘗試一次。
    • bypass_document_validation: 預設值False,設為True代表允許不合法的document被寫入。
  11. replace_one(filter, replacement, upsert=False, bypass_document_validation=False)
    • 取代一份符合filter條件的文件,傳回值為UpdateResult物件。
      • acknowledged: 當WriteConcern(w=0)時,acknowledged會傳回False,其他情況會傳回True
      • raw_result: 傳回值的原始資料。
      • matched_count: 符合update條件的documents的數量。
      • modified_count: 修改documents的數量。
      • upserted_ids: replace_one插入的documents的id。
    • filter: 要篩選的條件。
    • replacement: 要取代的文件。
    • upsert: 設為True會在找不到filter對應的文件時,插入一份新文件。預設為False
    • bypass_document_validation: 預設值False,設為True代表允許不合法的document被寫入。
  12. update_one(filter, update, upsert=False, bypass_document_validation=False)
    • 更新一份符合filter條件的文件,傳回值為UpdateResult物件。
      • acknowledged: 當WriteConcern(w=0)時,acknowledged會傳回False,其他情況會傳回True
      • raw_result: 傳回值的原始資料。
      • matched_count: 符合update條件的documents的數量。
      • modified_count: 修改documents的數量。
      • upserted_ids: replace_one插入的documents的id。
    • filter: 要篩選的條件。
    • update: 要修改的欄位和值。
    • upsert: 設為True會在找不到filter對應的文件時,插入一份新文件。預設為False
    • bypass_document_validation: 預設值False,設為True代表允許不合法的document被寫入。
  13. update_many(filter, update, upsert=False, bypass_document_validation=False)
    • 更新所有符合filter條件的文件,傳回值為UpdateResult物件。
      • acknowledged: 當WriteConcern(w=0)時,acknowledged會傳回False,其他情況會傳回True
      • raw_result: 傳回值的原始資料。
      • matched_count: 符合update條件的documents的數量。
      • modified_count: 修改documents的數量。
      • upserted_ids: replace_one插入的documents的id。
    • filter: 要篩選的條件。
    • update: 要修改的欄位和值。通常會用特殊語法。
    • upsert: 設為True會在找不到filter對應的文件時,插入一份新文件。預設為False
    • bypass_document_validation: 預設值False,設為True代表允許不合法的document被寫入。
  14. delete_one(filter)
    • 刪除一份符合filter條件的文件,傳回值為DeleteResult物件。
      • acknowledged: 當WriteConcern(w=0)時,acknowledged會傳回False,其他情況會傳回True
      • raw_result: 傳回值的原始資料。
      • deleted_count: 刪除的documents的數量。
    • filter: 要篩選的條件。
  15. delete_many(filter)
    • 刪除所有符合filter條件的文件,傳回值為DeleteResult物件。
      • acknowledged: 當WriteConcern(w=0)時,acknowledged會傳回False,其他情況會傳回True
      • raw_result: 傳回值的原始資料。
      • deleted_count: 刪除的documents的數量。
    • filter: 要篩選的條件。
  16. aggregate(pipeline, **kwargs)
    • 使用aggregate架構來運算。所有aggregate參數應該透過kwargs來傳入。傳回值是CommandCursor物件。
    • aggregate使用時會遵守read preference,如果有使用$$out pipeline,但read preference卻不是PRIMARY,會產生錯誤。
    • pipeline: a list of aggregation pipeline stages。
    • 常見的aggregate參數
      • allowDiskUse: 是否允許寫入暫存檔,設為True,aggregate stage會將暫存檔案寫入_tmp目錄,預設為False
      • maxTimeMS: 允許執行的時間(milliseconds)。
      • batchSize: 每次batch傳回documents的最大數量。
      • useCursor: 如果server有支援,要求server透過cursor提供結果。預設為True
  17. find(filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, modifiers=None, manipulate=True)
    • 查詢database,傳回符合filter條件的documents,傳回時只保留projection指定的欄位。find()會遵守read preference。
    • filter: 指定篩選條件的SON物件。
    • projection: 傳回結果要保留的欄位,除非指定_id:0,否則_id一定會包括在裡面。
    • skip: 要忽略前幾筆結果。
    • limit: 一次傳回的最大數量。
    • no_cursor_timeout: 預設值為False,當cursor閒置10分鐘就會被server斷掉。如果設為True,cursor永遠不會timeout,所以一定要手動close()才能正常關閉。
    • cursor_type: 選擇cursor類別。
      • NON_TAILABLE: 標準cursor。
      • TAILABLE: 用在capped collection上,當最後一筆資料讀取後不會關閉,而會停留在最後一筆document的位置。如果有新的document加入,可以再繼續讀新的資料。
      • TAILABLE_AWAIT: 當最後一筆資料讀取後,server會等一段時間再關掉cursor,這樣在query過程中插入的document也可以被讀出來。
      • EXHAUST: MongoDB會主動將資料送給client,而不會等client要求,這可以減少latency。
        • limit會被忽略。
        • sharded cluster不支援這種cursor。
    • sort: 指定(key, direction)來排序傳回的結果。
    • allow_partial_results: 設為True,如果shard nodes當機了,會傳回部分結果而不會產生錯誤。預設為False
    • oplog_replay: 設為True會設定oplogReplay query flag。
    • modifiers: 型態為dict,用來設定query modifier。
    • batch_size: 一次傳回的documents數量。
  18. find_one(filter_or_id=None, *args, **kwargs)
    • 查詢database,傳回一筆符合filter條件的document,找不到會傳回Nonefind_one()會遵守read preference。
    • 所有find()的參數都可以用在find_one(),除了limit
    • filter: 指定篩選條件的SON物件。
    • argskwargs: 代表find()可用的參數。
  19. find_one_and_delete(filter, projection, sort, **kwargs)
    • 查詢database,傳回一筆符合filter條件的document,並將document從資料庫刪除,找不到會傳回None。會遵守read preference。
    • filter: 指定篩選條件的SON物件。
    • projection: 傳回結果要保留的欄位,除非指定_id:0,否則_id一定會包括在裡面。預設為None
    • sort: 如果有多筆符合的document,要如何選擇。排序後的第一筆將被傳回及刪除。。預設為None
  20. find_one_and_replace(filter, replacement, projection, sort, return_document, **kwargs)
    • 查詢database,傳回一筆符合filter條件的document,並將document從資料庫刪除,插入新的document replacement,找不到會傳回None。會遵守read preference。
    • filter: 指定篩選條件的SON物件。
    • replacement: 要用來取代document。
    • projection: 傳回結果要保留的欄位,除非指定_id:0,否則_id一定會包括在裡面。預設為None
    • upsert: 設為True會在找不到filter對應的文件時,插入一份新文件。預設為False
    • sort: 如果有多筆符合的document,要如何選擇。排序後的第一筆將被傳回及刪除。。預設為None
    • return_document: 預設值為ReturnDocument.BEFORE,代表傳回被刪除的資料,如果找不到符合的會傳回None。設為ReturnDocument.AFTER則會傳回插入或取代的資料。
  21. find_one_and_update(filter, update, projection, sort, return_document, **kwargs)
    • 查詢database,傳回一筆符合filter條件的document,並用update的資料更新document。會遵守read preference。
    • filter: 指定篩選條件的SON物件。
    • update: 要更新的欄位和值。
    • projection: 傳回結果要保留的欄位,除非指定_id:0,否則_id一定會包括在裡面。預設為None
    • sort: 如果有多筆符合的document,要如何選擇。排序後的第一筆將被傳回及刪除。。預設為None
    • upsert: 設為True會在找不到filter對應的文件時,插入一份新文件。預設為False
    • return_document: 預設值為ReturnDocument.BEFORE,代表傳回被刪除的資料,如果找不到符合的會傳回None。設為ReturnDocument.AFTER則會傳回插入或取代的資料。
  22. count(filter=None, **kwargs)
    • 計算符合條件的document數量。
    • filter: 指定篩選條件的SON物件。
    • hint: 要使用的index name,可以同時有多個index,如[('index_a', pymongo.ASCENDING), ('index_b', pymongo.DESCENDING)]
    • limit: 要計算的最大數量。
    • skip: 要忽略前幾筆結果。
    • maxTimeMS: 這個命令允許執行的最長時間(milliseconds)。
  23. distinct(key, filter=None, **kwargs)
    • 計算key有幾種不同的值。
    • key: index key的名稱,如果不是字串會產生TypeError
    • filter: 計算時會篩選條件。
    • maxTimeMS: 這個命令允許執行的最長時間(milliseconds)。
  24. create_index(keys, **kwargs)
    • 建立一個index,可以一個key或由多個key組成,例如[('length', pymongo.ASCENDING), ('age', pymongo.DESCENDING)]代表由兩個key組成的index,這個index只有當filter同時出現length與age時,才會發揮作用。
    • keys: 字串代表一個key,或是一個list of tuple,代表多個key。
    • name: 這個index的指定名稱,設為None表示自動產生。
    • unique: 設為True表示key不會重複。
    • background: 設為True表示在背景執行,避免影響前景的query。
    • sparse: 設為True會忽略缺少指定key的documents。
    • bucketSize: 在geoHaystack index中,多少個documents會聚成一群來計算經緯度。
    • min: key的最小值。
    • max: key的最大值。
    • expireAfterSeconds: 如果key指定的欄位是UTC datetime,當現在時間與key值的時間相差超過expireAfterSeconds秒,就會自動刪除這份文件。
    • partialFilterExpression: 指定partial index。
  25. create_indexes(indexes)
    • 建立一或多個index。
    • indexes: list of IndexModel
  26. drop_index(index_or_name)
    • 從collection刪除指定的index,如果index不存在或collection不存在,會產生OperationFailure
  27. drop_indexes(): 刪除這個collection所有的index。如果collection不存在,會產生OperationFailure
  28. reindex(): 重建這個collection上所有的index。
  29. list_indexes(): 列出這個collection上所有的index。
  30. index_information(): 傳回dict包含{'index_name': information}
  31. drop(): 等同於db.drop_collection('name')
  32. rename(new_name, **kwargs): 修改collection的名稱。如果新的名稱已經存在,會產生InvalidName
  33. options(): 傳回collection可用的選擇及目前的值。
  34. group(key, condition, initial, reduce, finalize=None, **kwargs)
    • 類似SQL group by的操作。
    • key: 設為None表示整個文件都拿來當key。設為list of keys會由這些key作group-by。設為字串會由單一的key作group-by。
    • condition: 指定要考慮的row。
    • initial: aggregation counter object的初始值。
    • reduce: 表示aggregation function,格式為Javascript字串。
    • finalize: 每一個輸出物件都會呼叫此function。
  35. map_reduce(map, reduce, out, full_response=False, **kwargs)
    • 執行map/reduce操作,結果會存在新的collection。
    • map: map function,格式為Javascript字串。
    • reduce: reduce function,格式為Javascript字串。
    • out: 輸出的collection名稱或是out物件(dict)。
    • full_response: 設為True,會傳回命令完整的回應;預設為False,只傳回輸出的collection。
  36. inline_map_reduce(map, reduce, full_response=False, **kwargs)
    • 執行inline map/reduce操作,表示在server的RAM中操作,結果不會產生result collection,而會傳回list of documents。
    • map: map function,格式為Javascript字串。
    • reduce: reduce function,格式為Javascript字串。
    • full_response: 設為True,會傳回命令完整的回應;預設為False,只傳回list of documents。
  37. parallel_scan(num_cursors)
    cursors = collection.parallel_scan(4)
    threads = [threading.Thread(target=process_cursor, args=(cursor,)) for cursor in cursors]
    for thread in threads: thread.start()
    for thread in threads: thread.join()
    
    • 平行掃描整個collection,傳回可以平行處理的list of cursor。只要collection在過程中不要修改,每個document就會剛好出現一次。
    • num_cursors: 要傳回幾個cursor。
  38. initialize_unordered_bulk_op(bypass_document_validation=False)
    • 開始一個無序的batch write。這些write operation不會按照順序執行,但一定都會執行到。
    • bypass_document_validation: 預設值False,設為True代表允許不合法的document被寫入。
  39. initialize_ordered_bulk_op(bypass_document_validation=False)
    • 開始一個有序的batch write。這些write operation會按照順序執行,如果出錯,後面未執行的operation會被放棄。
    • bypass_document_validation: 預設值False,設為True代表允許不合法的document被寫入。

pymongo.cursor.Cursor

Overview

  • 不應該直接創造這個class的物件,應該由Collection.find()來傳回Cursor
  • cursor分為四類
    • NON_TAILABLE: 標準cursor。
    • TAILABLE: 用在capped collection上,當最後一筆資料讀取後不會關閉,而會停留在最後一筆document的位置。如果有新的document加入,可以再繼續讀新的資料。
    • TAILABLE_AWAIT: 當最後一筆資料讀取後,server會等一段時間再關掉cursor,這樣在query過程中插入的document也可以被讀出來。
    • EXHAUST: MongoDB會主動將資料送給client,而不會等client要求,這可以減少latency。

Methods and Members

  1. c[index]c.__getitem__(index)
    • 傳回index指定的documents,例如c[50]是傳回第50筆資料,c[20:25]相當於skip=20limit=5
    • 如果index是負數或超過最大值,會產生IndexError
  2. add_option(mask): 設定query flag的bitmask,mask是2的幂次。
  3. alive: 在一般cursor中,這個值沒有用。在TAILABLE cursor中,這個值用來判斷cursor是否被server關閉。
  4. batch_size(size): 一次batch傳回的document數量,這個值是唯讀的,應該在Collection.find()中設定。
  5. clone(): 傳回cursor的複製品,無論舊的cursor讀過多少資料,新的cursor內部的指標一定指向開頭。
  6. close(): 明確的關閉cursor。
  7. count(with_limit_and_skip=False)
    • 取得query的documents總數。
    • with_limit_and_skip: 設為True時,會考慮limitskip的值,預設值為False
  8. cursor_id: 一個long number代表id。
  9. distinct(key): 統計指定的key有幾種不同的值。
  10. explain(): 傳回explain plan record。
  11. hint(index): 新增一個hint,告訴Mongo要執行此query最適當的index。正確的設定可大幅增加query的效率,如果你查詢多個field,其中有一個有作index,就可以將此index作為hint。如果index不存在,不會產生錯誤。
  12. max(spec): 設定index的上限值,spec是list of (field, limit)。
  13. min(spec): 設定index的下限值,spec是list of (field, limit)。
  14. next(): 從cursor的buffer queue中讀取下一筆資料。
  15. remove_option(mask): 消除query flag的bitmask,mask是2的幂次。
  16. retrieved: 目前已從server讀取的資料總數,相當於應用程式已讀取的資料數,加上buffer queue中剩餘的資料數。
  17. rewind(): 讓cursor回到開頭,會保持目前cursor的所有設定。
  18. where(code): 在目前的query新增$$where述句,code是JavaScript expression,在每個document掃描時都會評估,只有傳回True的才會被讀取。